whois “Tasos Bitsios”

• Full stack software developer ~ 13 years
  • Somwehat backend-leaning
  • Mostly JS/TS/node.js/React
  • Mostly worked in startups
• Long time listener, first time speaker
• Developer @ Kadena Developer Experience team
• Socials:
  • @Takadenoshi on Github
  • @Takadenoshi on X

whois “Kadena”

• Scalabe PoW Blockchain
• Focus on:
  • scalability
  • intelligent & secure smart contracts
    • source available
    • formal verification
• Socials
  • @kadena-io and @kadena-community on Github
  • @kadena_io on X

Server-Sent Events (SSE)

A server-push protocol

• Unidirectional: Server -> Client
• Essentially a streaming HTTP/1.1 GET (or HTTP/2)
  • Connection is kept open, server writes more data as it becomes available
• (Web) Client side interacts with SSE endpoints using EventSource
  • Register data or custom event callbacks
  • A MessageEvent Interface
• With reconnection batteries included*
  • Terms and conditions may apply
• Very simple protocol

Use cases

Replaces polling. Stream any kind of update from the server.

• notifications
• live ticker data
• live sports events
• anything that is UTF-8 suitable

What is this new thing?

🥳 SSE is 19 years old

🔧 13 years of mainstream support

• 2004 Sep 23 · Server-sent DOM Events, Ian Hickson, Opera Software, WHATWG Web Applications 1.0
• 2006 · [Production] Opera browser implementation
• 2009 · W3C Working Draft, Ian Hickson, Google Inc
• 2010 · [Production] Safari v5, Chrome v6
• 2011 · [Production] Firefox v6,
• 2015 · W3C Recommendation

W3C Publication History

Current: HTML Living Standard § 9.2

Playground repo - download me!

Minimum Viable SSE response

The simplest server-sent event stream specifies just data events.

Example with 2 events:

> GET /stream/hello HTTP/1.1

  < HTTP/1.1 200 OK
  < Content-Type: text/event-stream

  < data: Hello\n\n

  < data: ReactLive are you there?\n\n

Content-Type is text/event-stream

Events separated by two newline characters \n\n

Data is encoded in UTF-8 (mandatory)

^{Playground: “simple” scenario}

Simple EventSource consumer

Server-sent events are consumed with EventSource:

let i=0;

  const source = new EventSource("http://localhost:3001/stream/simple");

  // "message" event emitted for each "data" event received
  source.addEventListener("message", (event) => console.log(++i, event.data), false);
  

The “minimum viable response” from the previous slide would trigger the callback twice, logging:

  1 Hello

  2 ReactLive are you there?

> GET /stream/hello HTTP/1.1

  < HTTP/1.1 200 OK
  < Content-Type: text/event-stream

  < data: Hello\n\n

  < data: ReactLive are you there?\n\n

Named Events

You can “namespace” your events using the event field with any custom name:

< event: goal
  < data: "ARS-LIV 1-1 45"\n\n

  < event: spectator-chat
  < data: "Did you see that ludicrous display just now"\n\n

The goal and spectator-chat events are handled separately on the frontend

• Allows multiplexing / routing events
  • no need for pattern matching on a shared data payload

Comments

Any lines starting with : (colon) are interpreted as comments

< data: this or that\n\n

  < :TODO emit some events in the near future

These are ignored on the client-side

Reconnection (1)

By default*, EventSource consumers will reconnect if the connection is interrupted.

^{* with implementation-specific caveats}

The default reconnection timeout is up to each browser (empirically: between 3-5 s.)

Custom timeouts

The reconnection timeout can be customized from the server-side by emitting a retry: field in any of the events.

retry: 2500
  data: Hello!\n\n
  

Value is in ms; timeouts are linear.

^{Playground: “Retry-flaky” scenario}

Reconnection (2)

Computer can say no

A server can signal “do not reconnect”:

• with a Content-Type header other than text/event-stream
• with a 2xx response other than 200
  • 301, 307 redirects to a 200 are OK

^{Playground: “Not SSE” scenario}

Reconnection (3) - Last-Event-ID

Events can include an id field with any UTF-8 string as value.

Connection interrupted? Reconnection header Last-Event-ID set to the last id received.

This allows the server to resume gracefully.

If this is the last event received in a stream that disconnects:

< id: data-0
  < retry: 5000
  < data: Data Zero event\n

Then the connection timeout will be 5 seconds, and the Last-Event-ID header will be set to data-0.

> GET /stream/notifications HTTP/1.1
  > Host: localhost:3001
  > Last-Event-ID: data-0

Minor caveat later on.

^{Playground: “notifications” scenario}

Full SSE response

> GET /stream/hello HTTP/1.1

  < HTTP/1.1 200 OK
  < Content-Type: text/event-stream

  < retry: 2000
  < id: 0
  < data: Hello\n\n

  < :I am a comment line

  < id: 1
  < event: status
  < data: {"warn":"Service degraded"}\n\n

More EventSource consumer

You can subscribe to custom events (e.g. status) with .addEventListener:

const source = new EventSource('/stream/hello');

  // [name]: triggers for custom named event, here: "status"
  source.addEventListener(
    "status",
    ({ data }) => console.log("custom event: status", JSON.parse(data)),
    false,
  );

  // as before, un-named data events
  source.addEventListener("message", (event) => { console.log("data event", event.data); }, false);

Subscribe to open and error for connection management:

source.addEventListener("open", (event) => { console.log("Connection opened"); }, false);

  source.addEventListener("error", (event) => { console.log("Connection error"); }, false);

The EventSource Interface

• constructor(url, { withCredentials: boolean })
  • withCredentials: instantiate with CORS credentials (default: false)
• Events:
  • open: on connection
  • error: on error/disconnection
  • message: on generic data: event received
  • <custom>: on named event received
• addEventListener(event_name: string, (event: Event) => void, bubbles: boolean)
• readyState: CONNECTING (0) | OPEN (1) | CLOSED(2)
  • CONNECTING: also “waiting to reconnect”
  • CLOSED: will not attempt to reconnect
• close()

MDN Reference

Error event is a bit useless

• Single bit of information: “error”

• callback signature is (event: Event) => void

  • event.target instanceof EventSource

• No reason or message can be derived

  • usually output in console

• Some disconnections can be “fatal”, cancelling the reconnection policy.

• Inspect readyState to find out EventSource’s intent:

  • CONNECTING: will reconnect / waiting to reconnect / reconnecting
  • CLOSED: will not reconnect

Implementation Considerations: HTTP/1.1 connections quota

Browsers implement a per-hostname connection quota (6) for HTTP/1.1

SSE over HTTP/1.1 may hit this easily with multiple tabs open

Per MDN:

Warning: When not used over HTTP/2, SSE suffers from a limitation to the maximum number of open connections, which can be especially painful when opening multiple tabs, as the limit is per browser and is set to a very low number (6). The issue has been marked as “Won’t fix” in Chrome and Firefox. This limit is per browser + domain, which means that you can open 6 SSE connections across all of the tabs to www.example1.com and another 6 SSE connections to www.example2.com (per Stackoverflow).

When using HTTP/2, the maximum number of simultaneous HTTP streams is negotiated between the server and the client (defaults to 100).

Solutions

• Prefer HTTP/2 where available (can-i-use 96% yes)
• If applicable, use an EventSource within a SharedWorker
  • shared by all tabs
• Use subdomains for SSE endpoint(s)

Implementation Considerations: Reconnecting

Default reconnection behavior implementation is not fully standardized

When a network error is encountered:

• Firefox: Will stop retrying (standard compliant)
• Chrome: Will keep retrying (actually helpful)

Consider handling reconnections yourself:

• Option for exponential backoff strategies
• Better connection timeout detection

Test it out in the playground repo:

• Start react-app but not the server
• Open react-app on Firefox
• Connect to any endpoint
• Firefox will attempt to reconnect once, encounter a network error, then stop
  • Chrome will instead keep reconnecting

Implementation Considerations: Proxies (1)

Proxies can kill

Proxies, load balancers and other networking middleware can kill idle connections after a short while.

Two approaches to fix this:

1/ Comment (not client-aware)

You can emit a comment (any line starting with a colon :)

< :bump

Good enough to keep connection alive.

EventSource won’t emit any event.

Implementation Considerations: Proxies (2)

Proxies can kill

Proxies, load balancers and other networking middleware can kill idle connections after a short while.

Two approaches to fix this:

2/ Heartbeat event (client-aware)

Emit a custom “heartbeat” or “ping” event every 15 seconds or so:

< event: heartbeat
  < data: ""

(data field must be present)

The client can listen to this event and use it to detect stale connections:

“expect heartbeats every N seconds, otherwise reconnect”

Preferred approach, especially for important payloads.

Implementation Considerations: Service Workers (Firefox)

Firefox Service Workers 💔 EventSource

Firefox has yet to implement support for EventSource in its Service Worker context.

Future people can track the present validity of this statement here.

✅ But you can use it in a SharedWorker

Implementation Considerations: Last-Event-ID detail

If no event is emitted in the subsequent connection’s lifetime, the Last-Event-ID is reset.

When a reconnected session is initialized with Last-Event-ID: Some-id

And the connection emits no messages for its lifetime,

Then the Last-Event-ID value is reset.

Vs competiting options

Kadena use case

Can I use?

Yes (96.11%)

https://caniuse.com/eventsource

Almost Done

References

§ 9.1 MessageEvent Interface - HTML Living Standard

§ 9.2 Server-Sent Events - HTML Living Standard

Links

Presentation

Presentation source & SSE playground - Github

Font

Monospace font: Kode mono by Kadena’s Isa Ozler